AD-A144  001  PROGRAMMING  GUIDE  FOR  SHIPBOARD  NUMERICAL  AND  PROGRAMS 
(SNAP) <U)  NAVAL  ENVIRONMENTAL  PREDICTION  RESEARCH 
FACILITY  MONTEREY  CA  T  BROWN  JUN  84  NEPRF-TR-84-06 

F/G  9/2 


i/1 


UNCLASSIFIED 


NL 


HAVENVPREDRSCHFAC  TR  84-06 


NAVENVPREORSCHFAC 
TECHNICAL  REPORT 
TR  84*06 


m 


PROGRAMMING  GUIDE  FOR 
SHIPBOARD  NUMERICAL  AID  PROGRAMS 

(SNAP) 


Terry  Brown 

Naval  Eavireaaeital  Pradictiaa  Research  Facility 


JUNE  1984 


DTIO 

AUG  0  3  1884 

E 

APPROVED  FOR  POIIIC  RELEASE;  DISTRIBUTION  IS  ONllMTEO 


84  08 


?,  07  6 


NAVAL  ENVIRONMENTAL  PREDICTION  RESEARCH  FACILITY 
MONTEREY,  CALIFORNIA  93943 


■ 


SECURITY  CLASSIFICATION  of  This  PAGE  (When  Dmtm  Entered) 


REPORT  DOCUMENTATION  PAGE 


VENVPRE 
TR  84- 


4.  title  (and  Submit) 


Programming  Guide  for  Shipboard 
Numerical  Aid  Programs  (SNAP) 


7.  AUTHOR/#.) 


READ  INSTRUCTIONS 
BEFORE  COMPLETING  FORM 


ms 


T73T 


S.  TYPE  OF  REPORT  ft  PERIOD  COVERED 

Final 


6.  PERFORMING  ORG.  REPORT  NUMBER 

TR  84-06 


B.  CONTRACT  OR  GRANT  NUMBER/#) 


Terry  Brown 


9.  PERFORMING  organization  name  and  adoress 

Naval  Environmental  Prediction  Research  Facility 
Monterey,  CA  93943 


II.  CONTROLLING  OFFICE  NAME  AND  ADORESS 

Naval  Air  Systems  Command 
Department  of  the  Navy 
Washington,  DC  20361 


4  MONITORING  AGENCY  NAME  8  ADDRESS!!/  dlttaranl  Iron  Controlling  Ollier) 


10.  PROGRAM  ELEMENT.  PROJECT.  TASK 
AREA  A  WORK  UNIT  NUMBERS 

PE  62759N  PN  WF59-551 
NEPRF  WU  6.2-34 


12.  report  oate 

June  1984 


It.  NUMBER  OF  PAGES 

32 


IS.  SECURITY  CLASS,  (ol  thla  raport) 

UNCLASSIFIED 


ISa.  DECLASSIFICATION/ DOWNGRADING 
SCHEDULE 


18.  DISTRIBUTION  STATEMENT  (ol  thla  Raport) 


Approved  for  public  release;  distribution  is  unlimited. 


17.  DISTRIBUTION  STATEMENT  (ol  lha  abalroct  antarad  In  Black  20.  II  dinar  ant  tram  Rapan) 


IS.  KEY  WORDS  /Continue  on  ravaraa  alda  It  nacaaaary  and  Idantlty  by  block  numbar) 

Programming  guide 
BASIC 

Human  Factors 


20.  A0STRACT  (Continue  on  r«v«n«  aide  II  neceeoery  md  Identity  by  block  number) 


Guidelines  for  programming  meteorological  applications  software  in  BASIC 
on  a  Hewlett-Packard  9845  desktop  computer  are  given.  These  guidelines  include 
control  structure,  programming  conventions,  and  a  human  factors  style  guide. 


DD  t  JAR1?!  1473  COITION  OF  I  NOV  •»  IS  O0SOLIT0 

S/N  0  102-014-  6601 


UNCLASSIFIED 


SECURITY  CLASSIFICATION  of  THIS  PAGE  /When  Data  Bntarad) 


CONTENTS 


L .  Scope  . 

1 . 1  Purpose  ...... 

1.2  Application  . 

2.  Reference  Documents  .... 

3.  .General  Requirements  .... 

3.1  Design  Requirements 

3.2  Program  Generation  . 

4.  Detailed  Requirements 

4.1  Program  Design  Requirements 

4.2  Programming  Guidelines 

4.2.1  Control  Structures 

4.2.2  Entry-Exit  Structure 

4.2.3  Size  . 

4.2.4  Branching 

4.2.5  Indentation  . 

4.3  Programming  Conventions 

4.3.1  Naming  .... 

4.3.2  Numerical 

4.3.3  Narrative  Description 

•4.3.4  Labels  .... 

4.3.5  Program  Control  Statements  . 

4.3.6  Specifications  and  Data  Statements 

4.3.7  Subprograms  . 

4.3.8  Abnormal  Termination  . 

4.3.9  Miscellaneous  . 

4.3.10  Special  Function  Keys  . 

4.3.11  Program  Overlays  . 

4.3.12  Default  Values  . 

5.  Human-Factors  Style  Guide  . 

5.1  Data  Entry  . 

5.1.1  Prompting  . 

5.1.2  Entering  Data  . 

5.1.3  Error  Check  . 

5.1.4  Editing  . 

5.2  Display  Screen  Design  . 

5.3  Menu-Driven  Programs  . 

Appendix  A  —  9845  Keyboard;  9845  CRT  Display  Screen 

Appendix  B  —  Glossary  . 

Appendix  C  —  Some  Simulated  Structured  Programming 
Constructions  in  HP  -  Basic 


CHANGE 

NUMBER 


DATE  OF  DATE  PAGE 

CHANGE  ENTERED  NUMBER 


ENTERED  BY 


1 


SCOPE 


1.1  PURPOSE 

This  document  establishes  a  programming  guide  for  all 
BASIC  code  developed  in  support  of  the  Shipboard  Numerical  Aid 
Program  (SNAP)  project.  This  document  illustrates  how  the 
guidance  of  MIL-STD-1679  shall  be  applied  to  SNAP  software  and  is 
modeled  after  reference  [2],  the  FORTRAN  Code  Development 
Standard  for  the  Tactical  Environmental  Support  System  (TESS). 

1.2  APPLICATION 

This  guide  shall  apply  to  all  BASIC  code  written  for  the 
Hewlett-Packard  9845  desktop  computer  as  part  of  the  SNAP 
project . 


In  this  document  the  word  "shall"  conveys  a  requirement 
while  the  word  "should"  conveys  a  suggestion. 


2 .  REFERENCE  DOCUMENTS 

Cl].  MIL-STD-1679,  Weapon  System  Software  Development, 
1  December  1978. 

[2].  FORTRAN  Code  Development  Standard  for  Tactical 
Environmental  Support  System,  August  1982. 
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3. 


GENERAL  REQUIREMENTS 


3.1  DESIGN  REQUIREMENTS 

Each  SNAP  shall  be  designed  to  meet  the  requirements 
described  in  the  applicable  Program  Performance  Specification 
(PPS)  if  such  document  exists.  The  PPS  describes  in  detail  all  of 
the  operational  and  functional  requirements  necessary  to  design  a 
specific  computer  program. 

3.2  PROGRAM  GENERATION 

All  SNAP  software  shall  be  coded  in  HP-BASIC  on  a 
Hewlett-Packard  9845  desktop  computer.  The  use  of  the  word  BASIC 
in  this  document  shall  mean  HP-BASIC.  Code  preferably  should  run 
on  both  the  A  and  B  models  of  the  9845  computer,  hereafter  called 
the  9845a  and  9845B.  Writing  separate  9845A  and  9845B  versions 
of  a  program  shall  be  avoided. 

In  some  cases,  a  program  may  be  written  specifically  for 
the  9845B  with  Option  275  installed,  hereafter  called  the  9845B- 
275.  Such  programs  will  not  run  on  a  9845A  or  a  9845B  that  does 
not  have  Option  275.  Programs  shall  be  written  specifically  for 
the  9845B-275  only  when  a  tactically  useful  version  of  the 
program  cannot  be  developed  for  the  9845A  or  9845B. 


4.  DETAILED  REQUIREMENTS 

4.1  PROGRAM  DESIGN  REQUIREMENTS 

Although  BASIC  is  not  a  structured  programming  language, 
SNAP  software  shall  adhere  as  much  as  practicable  to  the 
structured  programming  principles  listed  in  Appendix  B  (glossary) 
of  this  document.  Appendix  C  contains  examples  of  simulated 
structured  programming  constructions. 

4.2  PROGRAMMING  GUIDELINES 

The  following  design  and  coding  guidelines  shall  apply 
to  the  development  of  SNAP  software. 


4.2.1 


Control  Structures 


Programs  should  be  designed  and  coded  using  the  three 
fundamental  control  structures  presented  in  figures  1  through  3i 
sequence  of  operations  (assignment,  arithmetic  operation,  ...); 
conditional  branch  ( IF.  ..THEN... ) ;  and  repetition  of  operations 
(FOR. . .NEXT) . 


Figure  1.  Sequence  of  operations. 


Figure  2.  Conditional  branch. 


A  Structured  Programming  ROM  is  included  as  part  of 
Option  275  for  the  9845B.  This  ROM  extends  the  BASIC  language  to 
include  statements  for  structured  looping  (WHILE. ..END  WHILEr 
REPE AT . .  .UNT I L )  and  structured  decisions  ( I F . .  .THEN . . .  ELSE ; 
SELECT... CASE ) .  Since  these  statements  are  not  available  for  the 
9845A,  their  use  shall  be  limited  to  programs  designed 
specifically  for  the  9845B-275. 


4.2.2 


Entry-Exit  Structure 


Each  program  segment  (see  glossary  for  definition)  must 
have  one  entry  and  one  exit.  The  one  entry  shall  be  at  the  first 
executable  statement  of  the  segment.  The  one  exit  shall  be  a 
SUBEND,  RETURN,  or  FNEND  statement  at  the  end  of  the  segment. 

4.2.3  Size 

To  avoid  SNAP  to  TESS  program  conversion  problems,  the 
main  program  and  all  subprograms  should  not  exceed  one  hundred 
executable  statements.  This  conforms  to  a  requirement  in 
reference  [2].  In  addition,  the  use  of  many  short  program 
segments,  rather  than  a  few  large  segments,  results  in  better 
computer  memory  packing  efficiency. 

4.2.4  Branching 

Use  only  simple  integers  as  the  index  of  a  computed 
GO  TO.  For  example. 


ON  Index  GO  TO  1500,2000 
not 

ON  Index ( I )  GO  TO  1500,2000 


Note  that  the  computed  GO  TO  is  similar  to,  but  is  not  the  same 
as  the  CASE  control  structure. 

Do  not  use  a  branching  statement  (GO  TO;  ON  Index  GO  TO) 
to  pass  control  to  a  statement  that  is  in  a  different  program 
segment . 


4.2.5  Indentation 

Indentation  of  program  statements  shall  be  used  to 
improve  readability.  The  Structured  Programming  ROM  included  in 
the  9845B-275  contains  an  indentation  utility  which  performs  this 
formatting.  Programmers  without  access  to  this  utility  (9845A 
users,  for  example)  may  submit  unindented  code  which  will  be 
indented  at  NEPRF  using  the  Structured  Programming  ROM 
indentation  utility.  Figure  4  shows  an  example  of  the  Structured 
Programming  ROM  indentation  scheme. 


Before  Indention 


After  Indention 


4.3  PROGRAMMING  CONVENTIONS 
4.3.1  Naming 

Naming  conventions  shall  be  uniform  throughout  the  SNAP 
software.  For  example,  don't  call  the  same  temperature  "Temp"  in 
one  program  segment  and  "T"  in  another.  Use  meaningful  names  for 
program  segment  labels,  variable  names,  and  file  names.  Avoid 
acronyms  not  in  general  use.  Avoid  using  the  characters  zero  and 
one  in  names  unless  they  are  part  of  an  identifying  number.  To 
simplify  SNAP  to  TESS  program  conversions,  limit  names  to  six 
characters  or  less. 

Names  may  be  assigned  using  the  implicit  FORTRAN 
convention,  (i.e.,  starting  integer  and  character  variables  with 
one  of  the  letters  I-N).  This  convention  reduces  the  need  to 
refer  to  the  explicit  variable  declarations  at  the  beginning  of 
the  program  segment.  A  comment  statement  shall  be  used  to 
identify  programs  using  this  implicit  naming  convention. 


4.3.2 


Numer ica 1 


4. 3. 2.1  Constants 

Constants  shall  be  defined  rather  than  calculated  (e.g., 
use  Half=0.5  instead  of  Half=l/2  ).  Each  constant  shall  have  at 
least  one  more  significant  digit  than  any  variable  used  with  that 
constant.  For  example,  if  a  variable  is  entered  with  0.01 
precision,  then  any  constants  used  with  that  variable  shall  be 
defined  to  0.001  precision. 

4. 3. 2. 2  Mixed-Mode  Expression 

To  simplify  SNAP  to  TESS  program  conversions,  mixed-mode 
expressions  should  be  avoided.  Note  that  the  intrinsic  integer 
(1NT)  function  in  HP-BASIC  does  not  truncate  as  does  the  INT 
function  in  FORTRAN. 

4. 3. 2. 3  Grouping 

The  9845  automatically  deletes  unneeded  blanks  and 
parentheses  from  arithmetic  operations.  Comment  statements  shall 
be  used  to  clarify  the  order  of  evaluation  of  complex  operations. 

4. 3.2.4  Significant  Digits 

The  number  of  significant  digits  of  the  output  shall  not 
exceed  the  number  of  significant  digits  of  the  input.  Rounding 
by  the  programmer  shall  not  occur  until  the  final  computational 
step. 


SHORT  precision  variables  and  calculations  shall  be  used 
only  when  computer  memory  is  exhausted  and  program  overlays 
cannot  be  used.  In  all  cases,  the  accuracy  requirements  of  the 
PPS  must  be  met. 

4.3.3  Narrative  Description 

SNAP  programs  should  be  internally  documented  using 
comments  in  the  source  code.  Some  programs  may  exceed  the  memory 
capacity  of  the  computer  or  have  unacceptably  long  execution 
times  when  documented  to  the  extent  described  below.  With  the 
prior  approval  of  the  NEPRF  SNAP  principal  investigator,  such 
programs  shall  be  delivered  in  two  versions: 

1.  A  fully  documented  but  non-executable  version. 

2.  An  executable  version  stripped  of  comments. 


4. 3. 3.1  Abstracts 

Each  program  and  subprogram  shall  include  at  the 
beginning  of  the  executable  coding  a  textual  description  of  its 
inputs;  outputs;  purpose;  a  list  of  other  segments  called;  and  a 
list  of  all  calling  segments. 
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An  alphabetized  table  of  variable  names,  variable 
definitions  and  the  range  of  allowable  values  shall  be  included 
in  the  abstract. 

The  initial  abstract  of  the  main  program  segment  shall 
also  include  the  name  of  the  activity  or  company  which  developed 
the  program,  the  name  and  telephone  number  of  a  point  of  contact, 
and  the  date  of  the  last  program  modification. 

The  initial  abstract  shall  also  explain  the  convention 
used  for  latitude  and  longitude  if  applicable.  For  example, 
degrees  and  minutes  versus  decimal  degrees;  positive  and  negative 
degrees  versus  north  and  south  labels;  latitudes  varying  from  0 
to  90  versus  0  to  180;  and  longitudes  varying  from  0  to  180 
versus  0  to  360.  Figure  5  is  an  example  of  an  initial  abstract. 

4. 3. 3. 2  Comments 

Comments  shall  be  used  throughout  the  code.  Comments 
may  be  grouped  into  a  single  block  preceding  a  group  of  source 
statements  which  perform  a  related  procedure.  Use  l  instead  of 
REM  for  comments.  Blank  lines  used  for  spacing  should  also  use 
an  1  . 


4.3.4  Labels 

HP-BASIC  allows  program  lines  to  be  labeled  with  a 
unique  name.  Without  the  cross  reference  capability  of  the 
Structured  Programming  ROM,  however,  locating  these  labels  in  a 
long  program  can  be  time  consuming.  For  readability,  it  is  more 
efficient  to  use  line  numbers  than  labels.  A  composite  method  of 
using  labels  and  line  numbers  follows: 


30  GO  TO  1130  I  Set_up 


1130  Set_up:  l  initialize  all  variables 


This  lets  the  programmer  use  labels  until  the  program  is 
finished.  Then  line  numbers  are  inserted  and  the  labels  are  left 
in  place  to  aid  program  readability.  The  use  of  line  labels 
versus  line  numbers  is  left  to  the  programmer  since  NEPRF  has  a 
9845B-275  with  cross  reference  capability. 
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4.3.5 


Program  Control  Statements 


4. 3. 5.1  FOR. . .NEXT  Loops 

Do  not  exit  and  re-enter  the  range  of  a  loop.  Do  not 
perform  invariant  calculations  and  assignments  within  loops. 

4. 3. 5. 2  IF  Statements 

Do  not  make  equality  tests  (=)  on  floating  point  data 
unless  exact  equality  is  desired.  In  general,  use  a  tolerance 
test.  For  example, 

IF  (NOT(ABS(A-B)<=Tolrnc))  THEN  ... 


4.3.6  Specification  and  Data  Statements 

Explicitly  specify  the  OPTION  BASE  (usually  1)  at  the 
beginning  of  the  program. 

Variable  types,  (i.e.,  INTEGER,  REAL),  shall  be 
explicitly  declared  at  the  start  of  each  program  segment  and  in 
COMMON  statements.  Character  variables  shall  be  declared 
INTEGER.  Dimension  all  arrays  in  these  declaration  statements. 
Document  with  comments  any  redimensioned  arrays.  Alphabetize 
variable  names  within  declaration  statements.  Bracket 
declarations  with  blank  lines.  For  example, 


i 

COM  REAL  Altim,  Dval(lOO),  INTEGER  Count 
INTEGER  I,  J,  Day (31) 

INTEGER  Month? ( 12 ) 

REAL  Humid,  Press,  Temp (2, 10) 

1 


The  9845  computer  performs  all  operations  using  full- 
precision  (REAL)  accuracy.  The  conversion  to  and  from  an  INTEGER 
variable  type  slows  program  execution.  Another  problem  may  occur 
when  inverting  a  matrix  that  is  not  full  precision  since  rounding 
errors  will  affect  the  accuracy  of  the  results.  If  a  program  has 
an  unacceptably  long  execution  time  or  is  inaccurate  due  to 
rounding  errors  (as  determined  by  the  NEPRF  SNAP  principal 
investigator),  then  all  explicit  declarations  shall  be  preceded 
by  an  1  and  remain  in  the  code  as  comments. 


4 . 3 . 6 . 1  Labeled  COMMON 


HP-BASIC  does  not  provide  for  labeled  COMMON.  A  comment 
shall  be  used  to  distinguish  between  different  COMMON  blocks. 
For  example. 


1  common/temps/ 

COM  REAL  Airtmp,  Seatmp,  Wetblb 
1 

i  common/winds/ 

COM  REAL  Wnddir,  Wndspd 

Each  copy  of  the  "labeled"  COMMON  shall  be  the  same  length  and 
contain  the  same  variable  names. 

4. 3. 6. 2  DATA  Statements 

Comment  statements  shall  be  used  to  delineate  related 
groups  of  DATA  statements.  The  arrangement  of  information  that 
is  part  of  an  array  shall  correspond  to  the  array  dimensions. 
For  example. 


l 

REAL  Airtmp (3, 4) 


1 

l  Air  temps  Celsius 
i 

DATA  -15. 8, -12. 3, -8. 0,-5. 3 
DATA  0.4,3.5,12.4,15.0 
DATA  21.9,23.0,22.5,24.7 
1 

Information  that  is  not  part  of  an  array  shall  be  arranged  so 
that  each  DATA  statement  contains:  <5;  5?  or  10  items.  For 
example , 


l 

DATA  1,2,3,4,5,6,7,8,9,10 
DATA  11,12,13,14,15,16,17,18,19,20 
DATA  21,22,23,24,25 
DATA  26,27 
1 


4.3.7  Subprograms 

HP-BASIC  has  two  types  of  subprograms.  Subroutine 
subprograms  (CALL  syntax)  and  Function  subprograms  (FN  syntax). 
It  also  has  subroutines  (GOSUB  syntax).  Subprograms  are 
preferable  to  subroutines  due  to  their  similarity  to  FORTRAN 
syntax.  Multiple  points  to  which  the  program  may  return  from  a 
subprogram  shall  not  be  allowed. 


A  FUNCTION  shall  be  used  only  for  its  returned  value, 
e.g.,  do  not  modify  global  data  or  arguments  within  a  FUNCTION. 

Data  in  pass  parameter  lists  shall  be  ordered  so  that 
"given"  data  are  first,  "both"  (given  and  yielded)  data  are  next, 
and  "yielded"  data  are  last.  Alphabetize  parameters  within  their 
respective  grouping.  For  example, 

CALL  Demo{Constant,Given,Both, Result, Yielded) 


4.3.8  Abnormal  Termination 

System  errors  (see  glossary)  shell  not  abort  program 
execution.  These  errors  shall  be  trapped  using  the  ON  ERROR 
syntax  which  shall  transfer  program  execution  to  a  centralized 
error  routine.  A  maximum  of  one  STOP  statement  is  allowed  in 
each  SNAP  program  and  it  must  reside  in  this  error  routine.  This 
routine  shall  automatically  print  a  hard  copy  message  similar  to 
figure  6. 


Forward  the  following  message 
along  with  a  copy  of  your  data 
if  possible  to! 


MEPRF 

Attn:  SNAP 

WORK  UNIT  S.2-34 

MONTEREY, 

CA  93943 

MESSAGE 

THIS  IS  -t-NPU.  ICING  PROBABILITY  Code 
LAST  MOD:  (Now.  19S3> 
program:  INPUTS 

option:  input  radiosonde  data  set 
ERROR  MESSAGE:  ERROR  18  IN  LINE  3090 

END  OF  MESSAGE 


Figure  6.  Example  of  an  abnormal  termination  message. 
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4.3.9 


Miscellaneous 


Calculations  shall  use  the  MKS  unit  system  as  specified 
for  TESS  programs.  Input/output  may  be  in  other  unit  systems  if 
applicable . 

Explicitly  declare  the  units  to  be  used  in  trigonometric 
calculations  (  i.e.,  DEG,  RAD,  or  GRAD)  at  the  beginning  of  the 
program.  The  preferred  units  are  RADs  which  are  used  in  FORTRAN. 

Use  only  simple  integers  as  indices  and  subscripts. 
These  indices  shall  be  explicitly  declared  as  INTEGER  variables. 

Do  not  use  multiple  statements  (i.e.,  no  X=Y=SZ=3.14) . 

Initialize  every  variable,  usually  with  the  applicable 
default  value,  before  using. 

Do  not  depend  on  the  values  of  "local"  variables 
computed  on  a  previous  call  to  a  routine. 

Do  not  use  LET  in  assignment  statements. 

End  each  program  segment  with  a  line  of  i's  and  the 
words  END  SEGMENT  NAME.  Begin  each  program  segment  with  a  line 
of  I's  and  the  words  BEGIN  SEGMENT  NAME.  For  example: 

i n  in  m 1 1 1 1 1 1 1 in 1 1 1 1 1 u i m u m  end  analysis 

1  l  1  1  ! Ill  1 1  11  1  1! 1  1  m 1  1  111  i  1  1  l  1  1  111  1  BEGIN  FORECAST 


Explicitly  declare  MASS  STORAGE  IS  (usually  ":T15")  at 
the  beginning  of  the  program. 

Use  Y  and  N  for  replies  to  Yes/No  queries.  The  special 
function  keys  described  below  can  be  used. 

4.3.10  Special  Function  Keys 

The  9845  Special  Function  Keys  (SFK’s)  are  marked  kO 
through  kl5.  These  SFK's  can  be  defined  by  the  programmer  to 
perform  operations  with  a  single  keystroke.  The  use  of  SFK's  is 
encouraged.  To  maintain  consistency  with  existing  SNAPs  and  the 
integrated  Refractive  Effects  Prediction  System  (IREPS)  program, 
the  SFK  definitions  shown  in  figure  7  should  be  observed. 
Changes  or  additions  shall  be  documented  in  the  program  abstract. 
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KEY  e 

-C1**r  lino 
BACK-UP 
-Cont i nu* 

KEY  1 

-Cl **r  1 i  n* 

CONT  Option 
-Exocut* 

KEY  2 

-Cl **r  1 i n* 

EXIT  GRAPHICS 
-Ex«cut* 

KEY  3 

-Cl *ar  1  i  n* 

GRAPHICS 

-Exocut* 

KEY  4 

-C 1 *ar  1  i  no 
Prints**" PRINTER  OFF “ 
-Exocut* 


KEY  3 

-  C 1  •  or  1  in* 
Print*$*"PRINTER  ON* 
-Exocut* 

KEY  6 

-C 1 **r  1  i  no 
Y 

-Cont i nu* 

KEY  ? 

-C 1 **r  1 i no 
N 

-Cont i nu* 

KEY  8 

-C) *ar  1 i no 
CONT  Ropoot 
-Exocute 

KEY  9 

-C I  ear  I  i  no 
LOAD  "AUTOST" ,1 
-Exoc  ut  e 


Figure  7.  Existing  Special  Function  Key  definitions. 


KEY  0  implements  a  "back  up  one  step"  procedure  which 
allows  the  user  to  return  to  the  immediately  preceding  prompt.  A 


ing 

this  feature 

is  : 

100 

Date:  1 

enter 

dat  e 

110 

Rep  1 y*  = 

"TODA 

Y  " 

120 

INPUT  " 

ENTER 

DATE", 

130 

IF  Repl 

y *= " BACK-UP " 

140 

Date*=Repl y* 

158 

1 

160 

L  at :  ! 

e  nt  er 

1  at i »  u 

170 

Rep  1 y  *  = 

"NOT 

ENTERED 

180 

INPUT  " 

ENTER 

L  A  T  I  T  U 

190 

IF  Repl 

y**"BAO  -UP " 

200 

Lat *=Repl y* 

2  1  0 

1 

220 

Lor*:  ! 

e  n  t  e  r 

)  o  n  g  1 1 1 

Pop  1 y*x " NOT  ENTERED" 

INPUT  "ENTER  LONGITUDE", Reply* 
IF  Repl  ;.'*  =  " BACK-UP"  THEN  L  at 
Lon**Rep1 y* 


KEY  1  transfers  execution  to  the  program  line  labeled 
"Option".  Usually  this  label  marks  the  beginning  of  the  program 
segment  which  displays  the  main  menu.  Thus,  the  user  can  return 
at  any  time  to  the  main  menu. 

KEY  2  allows  printed  output  to  be  displayed  by  EXITing 
GRAPHICS.  This  is  more  applicable  to  the  9845A  which  does  not 
allow  simultaneous  display  of  text  and  graphics  as  does  the 
9845B-275. 


KEY  3  allows  plotted  output  to  be  displayed  by  enabling 
the  GRAPHICS  capability.  It  is  the  reverse  of  KEY  2. 

KEY  4  and  KEY  5  allow  the  user  to  specify  the  CRT  or  the 
internal  printer  as  the  output  device  by  assigning  the  variable 
named  Print$  a  value  which  is  checked  by  the  program.  The 
appropriate  PRINTER  IS  statement  is  then  executed.  For  example. 


IF  Print$=" PRINTER  ON"  THEN  PRINTER  IS  0 

or 

IF  Print$= "PRINTER  OFF"  THEN  PRINTER  IS  16 


KEY  6  and  KEY  7  let  the  user  answer  yes/no  questions 
with  one  keystroke  instead  of  two. 

KEY  8  is  used  in  the  IREPS  program  to  repeat  the  last 
output.  It  is  not  applicable  to  other  programs. 


KEY  9  re-starts  the  entire  program  run.  If  your  program 
does  not  use  the  AUTOSTart  capability  of  the  9845,  you  must 
change  the  word  "AUTOST"  to  the  name  of  the  first  program  you 
want  executed. 

4.3.11  Program  Overlays 

Overlays  (see  glossary)  shall  be  used  when  needed  to 
ensure  that  each  SNAP  can  be  loaded  into  the  memory  of  either  a 
9845A  or  9845B.  SNAPs  written  specifically  for  the  9845B-275  are 
exempt  from  this  requirement. 

When  a  program  is  divided  into  overlays,  the  program 
should  display  a  message  indicating  which  overlay  is  currently 
executing . 
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4.3.12  Default  Values 

The  ability  to  select  default  values  for  user  entries 
as  specified  in  the  PPS  shall  be  included  in  each  SNAP.  Default 
values  shall  be  displayed  to  the  user  and  be  selected  by  simply 
pressing  the  CONT  key.  Frequently,  defaults  represent  suggested 
values  for  data  that  is  difficult  for  SNAP  users  to  obtain. 

The  use  of  defaults  is  suggested  even  when  not  specified 
in  the  PPS.  For  example,  whenever  the  user  is  presented  a  list 
of  choices,  the  default  should  be  the  first  choice  in  the  list. 
This  follows  the  convention  of  the  IREPS  program.  It  follows  that 
the  default  for  Yes/No  questions  should  be  a  Yes  (Y). 


5.  HUMAN-FACTORS  STYLE  GUIDE 

Consider  the  following  human-factors  design  principles 
while  writing  SNAPs: 

Provide  immediate  and  obvious  feedback  to  the  user. 
Echo  all  user  entries. 

Be  consisten  .  For  example,  place  all  error  messages 
at  the  same  screen  location. 

-  Minimize  user  memory  demands.  Display  default  input 
values  to  the  user.  Menu  displays  help  the  user  make  choices. 

Simplify.  Use  short  prompts  and  incorporate  default 
values  into  the  program  whenever  possible.  Limit  the  number  of 
choices  the  user  must  consider  at  any  one  time. 

Match  the  program  to  the  user's  skill  level. 
Consider  what  the  user  is  expected  to  do,  what  decisions  need  to 
be  made  and  what  information  is  needed  to  make  those  decisions. 

Tell  the  user  where  he  is  and  how  to  get  back  to 
where  he  came  from.  Menu-driven  programs  do  this  by  providing  a 
main  menu  which  serves  as  a  home  base.  The  program  begins  with 
this  main  menu  from  which  the  user  can  select  various  options  and 
then  return. 
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Tell  the  user  what  is  happening.  Display  screens 
should  be  titled:  for  example,  "WIND  PROBABILITY  CALCULATION 
PROCEDURE".  If  a  section  of  the  program  takes  more  than  5 
seconds  to  execute,  tell  the  user  how  long  he  must  wait.  For 
example,  "Now  calculating  wind  probability  isopleths:  time 
required  is  2  minutes".  The  user  should  be  advised  of  the 
program's  progress  during  these  longer  operations.  For  example, 
"30  knot  probabilities  completed.  Now  doing  50  knot 
probabilities".  These  updates  should  be  displayed  at  about  30 
second  intervals. 

5 . 1  DATA  ENTRY 

The  following  guidelines  apply  to  programs  in  which  the 
user  enters  information  through  the  keyboard.  (The  9845  keyboard 
is  described  in  Appendix  A).  The  data  entry  process  should 
typically  consist  of  the  following  sequence  of  steps: 

program  displays  a  prompt 
user  enters  information 
program  echoes  the  entry  on  the  screen 
program  error  checks  the  entry 

program  displays  an  error  message  if  appropriate 
-  information  is  edited  as  needed 
information  is  accepted 

5.1.1  Prompting 

The  program  should  provide  a  prompt  for  every  data 
input.  Prompts  should  appear  in  the  Display  Line  (line  22)  of 
the  CRT. 


The  entry  format  should  be  displayed  in  inverse  video 
and  precede  the  instruction  to  the  user.  This  position  allows 
the  user  to  see  his  entry  displayed  directly  below  the 
format.  Generally,  use  the  character  "#"  to  show  formats  for 
digits  and  the  letter  "C”  to  show  formats  for  alphanumeric 
entries.  More  specific  formats  can  be  used.  For  example,  the 
format  for  a  calendar  date  entry  might  be  "MMDDYY"  for  Month, 
Day,  and  Year.  Established  formats,  such  as  the  World 
Meteorological  Organization  (WMO)  radiosonde  code,  may  be  used. 
For  example,  the  WMO  code  uses  "ddfff"  to  format  wind  direction 
and  speed  reports. 

Clarifying  instructions  and  entry  examples,  if  used, 
should  be  in  parentheses  immediately  following  the  user 
instruction . 

Range  limits  should  be  next  in  the  prompt  line  in 
braces  ({...}). 

Default  values  should  be  at  the  end  of  the  prompt  line 
in  brackets  ([...]).  For  example, 
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###.#  Enter  Temperature  (Celsius),  {-50  to  50},  [10]. 


where: 

###.#  is  the  entry  format  showing  that 

0.1  degree  precision  is  expected 
and  that  the  field  length  is  five 
places  including  sign  and  decimal 
point . 

Enter  Temperature  is  the  instruction  to  the  user. 

(Celsius)  is  a  clarifying  instruction. 

{-50  to  50}  is  the  range  of  acceptable  values. 

[10]  is  the  default  value  obtained  by 

simply  pressing  the  CONT  hey. 


Some  entries  may  require  more  explicit  instructions  than 
can  be  fit  in  the  Display  Line.  In  such  cases,  the  explanatory 
information  should  be  displayed  above  the  Display  Line  in  the 
Printout  Area.  The  explanatory  information  should  be  cleared 
from  the  screen  once  the  data  entry  has  been  completed.  The 
prompt  itself  should  still  follow  the  guidance  above. 

If  there  are  similar  or  identical  data  entry 
requirements  in  different  parts  of  the  program,  prompt 
consistently. 

5.1.2  Entering  Data 

Minimize  the  length  of  the  information  to  be  entered. 
For  example,  don't  make  the  user  enter  "SEPTEMBER"  when  the 
abbreviation  "SEP"  will  suffice.  If  data  consist  of  logically 
related  groups  (e.g.,  date-time  group),  permit  the  user  to  enter 
several  fields  together  instead  of  separately.  For  example, 
don't  make  the  user  enter  the  day  in  response  to  one  prompt,  the 
month  in  response  to  a  second  prompt,  and  the  year  in  response  to 
a  third  prompt.  Instead,  let  the  user  enter  the  day,  month,  and 
year  at  the  same  time  in  response  to  a  single  prompt. 

Data  shall  be  entered  in  the  appropriate  units.  For 
example,  since  tropical  cyclone  warnings  give  wind  speeds  in 
knots,  the  user  shall  enter  wind  speed  data  in  knots.  Conversion 
to  other  units  shall  be  done  by  the  program  and  be  documented 
with  comments. 

The  program  should  accept  both  upper  and  lower  case 
letters  interchangeably,  unless  differentiation  is  required.  For 
example,  the  user  should  be  able  to  enter  either  a  "Y"  or  a  "y" 
in  order  to  affirm  a  Yes/No  question. 
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5.1.3 


Error  Check 


Check  all  entries  for  errors.  Anticipate  possible 
errors  such  as  entering  a  letter  in  place  of  a  number.  Check 
all  entries  against  range  and  length  limits.  Catch  entries  which 
cause  illegal  program  actions  such  as  division  by  zero. 

When  errors  are  detected,  alert  the  user,  identify  the 
error,  and  tell  him  how  to  recover.  It  is  not  enough  to  beep  or 
display  the  word  "ERROR".  Alerting  signals  must  differ  from  the 
normal  background.  Using  beeps  and  flashing  messages  throughout 
the  program  will  reduce  their  value  in  error  routines.  Consider 
reserving  beeps  and  flashing  messages  for  errors. 

Error  messages  shall  be  placed  consistently  at  the  same 
screen  location,  just  above  the  Display  Line  is  a  good  place.  The 
message  shall  show  the  erroneous  entry.  The  message  shall  tell 
what  is  wrong  —  for  example,  that  the  entry  is  too  long  —  and 
what  to  do  —  for  example,  abbreviate  month  with  three  letters. 
An  example  of  a  helpful  error  message  is  shown  below. 


ERROR.  Date  2/31/83  contains  invalid  day. 
MM/DD/YY  Enter  date. 


Some  errors  are  more  serious  than  others.  For  example, 
a  program  that  allows  a  user  to  purge  files  with  a  single 
keystroke  is  a  disaster  waiting  to  happen.  Protect  the  user  in 
such  cases  by  making  data  entry  require  two  stages.  When  the 
user  makes  a  potentially  disastrous  entry,  display  a  new  message 
describing  the  consequences.  The  user  should  be  given  a  chance 
to  continue  or  back  out.  Such  a  display  is  shown  below. 


**  WARNING  ** 

You  have  selected  the  "PURGE  FILES"  option. 

Your  data  files  will  be  purged  if  you  continue. 

C  ABORT  the  PURGE  FILES  option?,  (Y/N),  [Y] 


5.1.4  Editing 

Permit  the  user  to  edit  entries  before  the  program 
accepts  data  for  calculations.  In  some  programs,  data  should  be 
edited  at  more  than  one  stage:  during  initial  entry,  after  a 
block  of  related  entries  have  been  made,  and  after  the  data  have 
become  part  of  a  database  (if  applicable). 


The  9845  automatically  allows  editing  during  initial 
entry.  The  user's  entry  is  displayed  as  it  is  typed  in  the 
Keyboard  Entry  Area  (lines  23-24)  of  the  CRT.  It  can  be  edited 
using  the  display  and  character  editing  keys  until  the  user 
presses  the  CO NT  key.  In  addition,  a  "back  up  one  step" 
procedure  can  be  included  in  each  program  to  allow  the  user  to 
return  to  the  immediately  preceding  prompt  and  re-enter  the  data. 
This  feature  can  be  programmed  into  Special  Function  Key  0  as 
described  in  section  4.3.10.  When  the  user  sees  that  the  echo  of 
his  entry  is  a  mistake,  the  backup  utility  offers  a  quick  fix. 

This  back  up  utility  doesn't  help  when  the  user  does  not 
see  the  mistake  until  several  other  entries  have  been  made.  In 
block  editing,  the  program  displays  a  related  group  of  entries 
and  also  displays  a  prompt  asking  if  the  user  wants  to  edit  any 
of  them.  If  the  user  does  want  to  edit,  he  defines  the  entry  to 
be  changed,  usually  by  entering  a  line  or  index  number.  The  user 
is  prompted  to  re-enter  the  indicated  data.  When  the  user 
indicates  that  no  more  changes  are  needed,  the  program  moves  on 
to  the  next  step. 

Editing  a  database  can  be  done  with  a  separate  utility 
program  or  as  a  part  of  the  SNAP  itself.  In  some  SNAPs,  data 
entered  and  stored  on  tape  during  a  previous  program  execution 
are  read  and  displayed  for  editing  before  continuing  with  a  new 
execution . 

5.2  DISPLAY  SCREEN  DESIGN 

Users  generally  find  it  easier  to  read  stationary  pages 
than  moving  pages.  The  9845  will  begin  scrolling  once  the  20 
Printout  Area  lines  of  the  screen  are  filled.  (The  9845  CRT 
display  screen  is  described  in  Appendix  A).  Instead  of 
scrolling,  it  is  preferable  to  clear  the  screen  before  putting  up 
a  new  display. 

Most  displays  should  be  titled  at  the  top-center  of  the 
screen.  In  addition  to  a  title,  most  displays  will  contain  other 
information  such  as  entry  echoes,  prompt  line,  error-messages, 
etc.  A  separate  screen  area  should  be  allocated  for  each 
information  category.  Information  should  not  stray  from  its 
assigned  area.  Try  to  separate  each  area  of  the  screen  from  the 
next  with  rows  or  columns  of  blank  spaces  or  with  lines. 

Determine  what  information  the  user  needs  at  each  point 
in  the  program  and  display  only  that.  Each  screen  should  convey 
one  logically  connected  thought  or  step. 

Follow  prevailing  conventions.  Numeric  information 
usually  should  be  displayed  in  tabular  format,  i.e.,  beneath 
column  headings  from  top  to  bottom.  If  the  user  is  entering  data 
from  a  standardized  form,  the  display  should  mimic  the  layout  of 
that  form. 


Data  shall  be  displayed  in  the  appropriate  units  as 
specified  in  the  PPS.  Usually  these  are  the  same  units  used  for 
entering  input. 

Display  information  in  a  recognizable  order.  Long  lists 
should  be  shown  in  an  order  familiar  to  the  user.  For  example, 
alphabetic,  numeric,  or  chronological  order.  In  menus,  the  most 
frequently  selected  options  should  be  listed  at  the  top  and  the 
infrequent  selections  should  be  at  the  bottom. 

Text  should  be  left  justified.  Numeric  information 
normally  should  be  right  justified.  Where  the  number  of  decimal 
places  varies  on  successive  lines,  decimal  points  on  all  lines 
should  align  at  a  particular  tab  value. 

5 . 3  MENU-DRIVEN  PROGRAMS 

SNAPs  should  generally  be  menu-driven  programs  since 
menus  make  few  demands  on  human  memory,  are  easy  to  learn,  and 
always  show  the  user  the  possible  paths  to  follow. 

The  menu  should  have  three  parts:  title,  list  of  menu 
choices,  and  a  prompt  line.  The  menu  title  should  be  centered  at 
the  top  of  the  display  and  should  end  with  the  word  "menu".  The 
prompt  generally  should  be  displayed  in  the  default  9845  Display 
Line  at  the  bottom  of  the  screen.  The  prompt  should  be  brief. 
The  following  is  a  sample  menu. 


MAIN  MENU 

Select  one  of  the  following  actions  by  entering  its  number 


1 .  ENTER  DATA 

2.  GENERATE  REPORT 

3 .  EDIT  DATA 

4.  START  NEW  FILE 

5.  PURGE  FILE 

6.  QUIT 

#  Enter  Choice,  {1-6},  Cl]. 


Menu  selection  should  be  done  by  entering  a  number.  The 
default  should  be  the  first  choice.  The  9845a  does  not  allow 
cursor  selection.  Programs  written  solely  for  the  9845B-275 
may  use  cursor  selection.  When  using  numbers  in  menus,  avoid 
their  use  in  nonmenu  displays.  If  you  are  displaying  a  list  of 
instructions,  for  example,  precede  each  instruction  by  a  hyphen 
instead  of  a  number.  Confusion  can  be  reduced  by  titling  menus 
as  menus  and  titling  other  displays  appropriately. 
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9845  KEYBOARD 

The  layout  of  the  9845  keyboard  is  shown  below. 


Display  Keys 

Edit  System  Command  Keys  _  f 


Typewnte^Keys 


Special  Function  Keys 
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Alphanumeric  Keys 


Program  Control  Keys 


Numeric  Keys 


9845  CRT  DISPLAY  SCREEN 

The  CRT  is  divided  into  several  areas: 

-  Printout  area  (lines  1-20)  is  used  for: 

>  echoing  user  entries 

>  instructions  and  background  information 

>  tabular  displays  and  menus 

>  error  messages 

>  other  messages 

-  Display  line  (22)  is  used  for: 

>  input  prompts 

>  short  messages  generated  by  DISP  statement 

-  Keyboard  entry  area  (lines  23-24)  is  used  for: 

>  user  entries 

-  System  comments  line  (25)  is  used  for: 

>  system  error  messages  and  indicators 


The  9845B  option  275  also  has  a  CRT  area  for  soft  key 
labels.  Programs  written  solely  for  the  9845B-275  may  use  this 
capability. 

The  CRT  display  screen  is  shown  below. 


Linas  1  -20 


Printout  Area 


}  Blank  Lina 

Line  22  }  Display  Line 

Lines  23-24  }  Keyboard  Entry  Area 

Line  25  }  System  Comments  Line 
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Abstract 
Calling  Program 


Construction 

Control  Structure 
Default  Value 

Function  Subprogram 

Main  Program 

MKS  Unit  System 

Operand 

Program 

Program  Segment 


GLOSSARY 

A  condensed  description  or  summary  of  a 
computer  program. 

When  a  subprogram  is  being  executed,  the 
program  segment  (either  main  program  or 
subprogram)  which  calls  the  subprogram  is 
the  calling  program.  Control  returns  to 
the  calling  program  when  the  called 
program  is  completed. 

A  group  of  logically  related  BASIC 
statements. 

Another  term  for  a  construction. 

The  value  assigned  to  a  variable  when  the 
user  does  not  enter  any  information  in 
response  to  a  prompt  but  simply  presses 
the  CONT  key. 

A  program  segment  that  returns  a  single 
numeric  or  character  string  value  to  the 
calling  program.  It  is  similar  to  a 
FORTRAN  FUNCTION. 

The  part  of  a  program  from  which 
subprograms  can  be  called.  Subprograms 
cannot  call  the  main  program. 

Unit  system  using  meters  for  length, 
kilograms  for  mass,  seconds  for  time,  and 
kelvins  for  temperature.  Other 
acceptable  units  are  Celsius  degrees  for 
temperature  and  millibars  for  pressure. 

A  quantity  entering  into  or  arising  from 
an  operation;  it  may  be  an  argument,  result, 
parameter,  or  the  location  of  the  next 
instruction. 

The  complete  sequence  of  coded 
instructions  and  data  necessary  to  solve 
a  problem. 

An  independent  group  of  program 
statements.  The  main  program  and  each 
subprogram  are  program  segments. 
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Structured  Programming  A  programming  technique  using  the 

following  concepts: 

(1)  Program  uses  only  the  three 
control  structures  of  a  simple  sequence 
of  operations;  a  conditional  branch;  and 
a  repetition  of  an  operation. 

(2)  Program  uses  limited  or  no 
"GO  TO"  logic. 

(3)  Program  is  divided  into  constituent 
parts  and  these  parts  are  divided  into 
their  constituents.  This  breakdown 
continues  until  a  level  is  reached  where 
there  is  no  subservient  level.  Lower 
levels  do  not  call  higher  levels. 

Subprogram  A  group  of  statements  that  performs  a 

certain  task  under  the  control  of  the 
calling  program  segment.  It  differs  from 
an  HP-BASIC  subroutine  (GOSUB... RETURN 
syntax)  since  it  is  a  seperate  segment 
which  comes  after  the  main  program. 

Subroutine  A  group  of  HP-BASIC  statements  which  can 

be  accessed  from  different  places  in  a 
program  segment.  The  subroutine  is  part 
of  that  program  segment. 

Subroutine  Subprogram  A  program  segment  that  performs  a 

specific  task  but  is  not  part  of  the 
calling  program.  It  is  similar  to  a 
FORTRAN  SUBROUTINE  and  can  return  more 
than  one  (or  none)  numeric  or  string  values. 

System  Error  An  error  detected  by  the  9845  operating 

system  which  normally  causes  program 
execution  to  cease.  These  errors  are 
numbered  and  an  error  message  is 
automatically  displayed  which  identifies 
the  error  type. 
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Programing  Constructions  in  HP  -  BASIC 


Some  Simulated  Structured 
CONSTRUCTION  TYPE 

1.  IF. . .THEN  single  statement 

2.  IF... THEN  multiple  statement 

3.  IF... THEN... ELSE 


4.  Multiway  selection,  ELSE  IF 


HP-BASIC  IMPLEMENTATION 

100  IF  condition  THEN  statement 

80  IF  NOT  condition  THEN  GOTO  100 
.  statements 


100  i  END  IF 

20  IF  NOT  condition  THEN  GOTO  50 
.  statements-1 


• 

40  GOTO  100 
50  !  ELSE 
.  statements-2 


100  !  END  IF 

20  IF  NOT  condition-1  THEN  GOTO  50 
.  statments-1 


• 

40  GOTO  150 
50  !  ELSE 

60  IF  NOT  condition-2  THEN  GOTO  90 
.  statements-2 


• 

80  GOTO  150 
90  !  ELSE 

100  IF  NOT  condition-3  THEN  GOTO  130 
.  statements-3 


120  GOTO  150 
130  1  ELSE 

.  statements-4 


150  I  END  IF 
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5.  Multiway  selection,  CASE 


20  IF  variable  <  1  THEN  GOTO  140 
30  IF  variable  >  3  THEN  GOTO  140 
40  CN  variable  GOTO  50,  80,  110 
50  !  CASE  1 
.  statements-l 


• 

70  GOTO  160 
80  !  CASE  2 
.  statements- 2 


100  GOTO  160 
110  !  CASE  3 

.  statements-3 


130  GOTO  160 
140  !  ELSE 

.  statements 


6.  DO  WHILE  repetition 


160  I  END  CASE 

20  IF  NOT  condition  THEN  GOTO  60 
.  statements 


7.  DO  UNTIL  or  REPEAT  repetition 


50  GOTO  20 
60  <  END  WHILE 

20  J  REPEAT 


8.  DO  FOR  repetition 


50  IF  NOT  condition  THEN  GOTO  20 

20  FOR  I  =  L  TO  M  STEP  N 
.  statements 


50  NEXT  I 

Note:  If  a  program  using  these  contructions  is  stripped  of  comments  by  a 
comment  deleting  utility  program,  then  the  destination  lines  listed  in  the  GOTO 
statements  will  be  deleted  and  the  program  will  not  run.  The  programmer  may 
need  to  use  line  labels  to  avoid  this  problem.  For  example,  instead  of  the 
syntax  shown  in  example  3  above,  use: 

20  IF  NOT  condition  THEN  GOTO  Line_50 
.  statements-l 

• 

40  GOTO  Line_100 
50  Line_50:  !  ELSE 
.  statements-2 

• 

100  Line  100:  SEND  IF 
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